org.globalplatform.contactless
Interface CLAppletActivationPolicy

All Superinterfaces:

javacard.framework.Shareable

public interface CLAppletActivationPolicy
extends javacard.framework.Shareable

An Application may implement and expose this interface to indicate whether it can be activated or not and to return a reason code together with the list of Applications preventing the activation. This interface allows an application provider to implement a specific Activation Policy for its application.

A reason code is coded on 2 bytes. The range from '0000' to '7FFF' is reserved for GlobalPlatform.

Such an application may expose the CLAppletActivationPolicy interface object(s) through Applet.getShareableInterfaceObject(javacard.framework.AID, byte) with the parameter set to GPCLSystem.GPCL_CL_APPLICATION_ACTIVATION_POLICY.

NOTE: A client Application should never store a reference to an object implementing this interface, as this would prevent the deletion of the Application owning this object.

Since:

export file version 1.2

Field Summary

static short	REASON_BUSINESS_POLICY_CONFLICT The Application cannot be activated because its business policy conflicts with some Applications that are already activated.
static short	REASON_UNSPECIFIED The Application cannot be activated for unspecified reasons.
static short	REASON_USER_NOT_VERIFIED A successful user verification (ex: PIN validation) is required prior to the Application being activated.

Method Summary

boolean	acceptActivation() Checks whether the Application exposing this interface accepts an activation request for itself or, if the Application implementing this interface is a CREL Application, for a referencing Application.
short	getNextApplicationConflictInfo(byte[] out, short outOffset) Retrieves TLV-encoded policy conflict information, which consists of one or several conflict reason codes and, for each of them, of a list of currently activated Applications conflicting with the Application implementing this interface for that particular reason.

Field Detail

REASON_BUSINESS_POLICY_CONFLICT

static final short REASON_BUSINESS_POLICY_CONFLICT

The Application cannot be activated because its business policy conflicts with some Applications that are already activated.

See Also:

Constant Field Values

REASON_USER_NOT_VERIFIED

static final short REASON_USER_NOT_VERIFIED

A successful user verification (ex: PIN validation) is required prior to the Application being activated.

See Also:

Constant Field Values

REASON_UNSPECIFIED

static final short REASON_UNSPECIFIED

The Application cannot be activated for unspecified reasons.

See Also:

Constant Field Values

Method Detail

acceptActivation

boolean acceptActivation()

Checks whether the Application exposing this interface accepts an activation request for itself or, if the Application implementing this interface is a CREL Application, for a referencing Application.

If a request is made to activate an Application, and this Application exposes this interface, then the OPEN shall invoke this method to check whether the Application accepts the activation request, except if the activation request originates from the Application itself. The OPEN shall call this method before processing the Protocol Parameter Conflict Detection Procedure. In the case of an Application Group, the OPEN is only expected to call this method on the Head Application.

Depending on the application provider policy, if the Application exposing this interface is a Head Application, then the implementation of this method may check whether associated Member Applications (also implementing and exposing this interface) accept the activation request. If one of its Member Applications rejects the activation request (because of some proprietary policy), then the Head Application may also reject the activation request.

Depending on the application provider policy, if the Application exposing this interface is referencing CREL Applications, then the implementation of this method may check whether referenced CREL Applications (also implementing and exposing this interface) accept the activation request. If one of the CREL Applications rejects the activation request (because of some proprietary policy), then the Application may reject the activation request.

The JCSystem.getPreviousContextAID() method allows the Application exposing this interface to discover the caller of this method:

• If the JCSystem.getPreviousContextAID() method returns null, then this method is invoked by the OPEN, otherwise it is invoked by another Application.
• If this method is invoked by the OPEN or the Application implementing this interface is NOT a CREL Application, then the Application shall check whether it can be activated or not. The Application should not modify its Contactless Activation State.
• If the Application implementing this interface is a CREL Application and this method is invoked by another Application, then the CREL Application checks whether some policy prevents the activation of the caller Application.

When this method is invoked, any policy conflict information previously computed by the Application implementing this interface shall be discarded. When rejecting the activation request, this method shall build new policy conflict information that may be subsequently retrieved using the getNextApplicationConflictInfo(byte[], short) method.

Returns:

true if the Application accepts the activation request, false otherwise.

getNextApplicationConflictInfo

short getNextApplicationConflictInfo(byte[] out,
                                     short outOffset)

Retrieves TLV-encoded policy conflict information, which consists of one or several conflict reason codes and, for each of them, of a list of currently activated Applications conflicting with the Application implementing this interface for that particular reason.

This method shall write TLV-encoded policy conflict information in the out buffer. Tag '48' shall be used to indicate a 2-byte conflict reason code and tag '4F' shall be used to indicate the AID of a conflicting Application. One or several conflict reason codes may be present, each of them followed by a list of Applications conflicting for that particular reason.

Example: '48 02 xx xx 4F (L) xx ... xx 4F (L) xx ... xx 48 02 xx xx 4F (L) xx ... xx 4F (L) xx ... xx 4F (L) xx ... xx ... ...'

This method shall be invoked one or several times until all data (policy conflict information) have been retrieved. The following behaviors shall be implemented:

• If there are no remaining data, then this method shall return 0, indicating to the caller of this method that all data were retrieved, and all policy conflict information shall be discarded. In particular, this behavior shall apply when all remaining data were retrieved by a previous call to this method, or when no prior call to the acceptActivation() method was performed, or when the call to the acceptActivation() method returned true (i.e. no conflict detected).
• If there are remaining data but none of these data can be consistently written to the out buffer without causing an array out of bounds access, then this method shall throw an ArrayIndexOutOfBoundsException, indicating to the caller of this method that more buffer space is required to retrieve remaining data.
• If there are remaining data and at least some of these data can be consistently written to the out buffer without causing an array out of bounds access, then this method shall write as much data as possible without causing an array out of bounds access and shall return the number of bytes written to the out buffer. If all remaining data were actually written the out buffer, then a subsequent call to this method (returning 0) will be needed for the caller to discover that all data were retrieved.

Depending on the application provider policy, if the Application exposing this interface is a Head Application, then the implementation of this method may retrieve conflict information from associated Member Applications (also implementing and exposing this interface) that previously rejected the activation request.

Depending on the application provider policy, if the Application exposing this interface is referencing CREL Applications, then the implementation of this method may retrieve conflict information from the CREL Applications (also implementing and exposing this interface) that previously rejected the activation request.

Parameters:

out - byte array buffer where policy conflict information shall be written. This buffer must be global.

outOffset - starting offset within the out byte array.

Returns:

the number of bytes written in out buffer.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If writing remaining data (even partially) to the out buffer would cause an array out of bounds access.